-------------------------------------------------------------------------------- -------------------------------------------------------------------------------- Author: Eric Gessner Date: 6/5/97 Email: 75700.1057@compuserve.com NOTE: Any/all feedback will be appreciated. I'm looking for a new job if you can help please let me know. This document describes a C++ DirectX error handler. It may or may not be helpful to you (check it out). I coded it to be portable. I used standard include files, functions, and data types. I included the source files (dxerror.cpp, .h). I intended for this to be compatible with most C++ compilers (if its not you have the src). -------------------------------------------------------------------------------- CONTENTS -------------------------------------------------------------------------------- 1) OverView/Purpose. 2) Files Provided. 3) Design Notes. 4) Error Types and Amplifying Data Constraint. 5) Examples/Use. -------------------------------------------------------------------------------- 1. OverView/Purpose. -------------------------------------------------------------------------------- This DirectX error handler was written in C++ and is designed for use with the DirectX 3. The file containing the error data (dxerror.dat) contains data derived from error constants, error values, and helpfile information for DirectX 3. You (*)may be able to use it for previous versions of DirectX. This DirectX Error Handler Provides the following functionality: 1) Lookups Up DirectX error data (contained in a file) for the error. 2) Display a MessageBox with the following information: a) The constant identifier (e.g. "DDERR_ALREADYINITIALIZED"). b) A description of the error (as contained in the help file). c) Amplifying Data (user supplied amplifyies origin or nature). 3) The error handler will automatically call a user supplied clean up function (when a clean up function supplied). (*)Note: DirectX 3 represents the error values (most of them) in 32 bit format. The error data is formatted via calls to a DirectX MAKE_DDHRESULT() macro which in-turn calls Windows MAKE_HRESULT() macro. (MAKE_DDHRESULT is defined in the dx header files and MAKE_HRESULT() is defined in winerror.h, see dx header files and winerror.h for details). If this method has changed from earlier DirectX versions this Error Handler won't work with them because the values used to retrieve error information are based on the method described above). -------------------------------------------------------------------------------- 2. Files Provided. -------------------------------------------------------------------------------- You need 3 files dxerror.cpp, dxerror.h, and dxerror.dat. The DxErrorHandler::GetErrorData() member function expects the dxerror.dat to be in the current/working directory. FILES DESC --------------- ---------------- (1) dxerror.h - header file. (2) dxerror.cpp - source file. (3) dxerrors.dat - error data file. (4) dxerror.lib - Borland Ver 5.01 library. (5) errordoc.txt - this file. -------------------------------------------------------------------------------- 3. Design Notes. -------------------------------------------------------------------------------- DxError was designed to encapsulate functionality for an error. DxErrorHandler was designed to encapsulate handling DxErrors. These classes can be easily modified to extend the error handling capability. -------------------------------------------------------------------------------- 4. Error Types and Amplifying Data Constraint. -------------------------------------------------------------------------------- The following DxErrorTypes are defined. --------------------------------------- DXERR_FATAL DXERR_WARNING DXERR_ANYERROR Use 60 Characters Maximum for Amplifying Data. ---------------------------------------------- MAX_DXERR_AMPLIFYING_DATA_LEN 60 -------------------------------------------------------------------------------- 5. Examples/Use. -------------------------------------------------------------------------------- Error information is obtained via a call to the HandleDxError() member function. The HandleDxError() member function takes up to 4 (four) parameters: Parameter Description --------- ---------------------------------------------------------------- p1 The DX error value (the result returned from the DX function). p2 The DxErrorType (DXERR_FATAL, DXERR_WARNING, or DXERR_ANYERROR). p3 Amplifying Data (something meaningful like its origin, etc). p4 Function to Call (the function you want to call if error occurs). Overloaded HandleDxError Function (call it passing desired params) --------------------------------- MyErrHandler.HandleDxError(p1); MyErrHandler.HandleDxError(p1, p2); MyErrHandler.HandleDxError(p1, p3); MyErrHandler.HandleDxError(p1, p4); MyErrHandler.HandleDxError(p1, p2, p3); MyErrHandler.HandleDxError(p1, p2, p4); MyErrHandler.HandleDxError(p1, p3, p4); MyErrHandler.HandleDxError(p1, p2, p3, p4); ---------- EXAMPLE 1: ---------- #include "dxerror.h" //include the header and make sure the compiler can //find the dxerror.lib file to link in. void MyFunction() { LPDIRECT3DRM lplpD3DRM; HRESULT dxresult; //HRESULT is DWORD, 32 bits for the result dxresult = Direct3DRMCreate(&lplpD3DRM); if (dxresult != D3DRM_OK) { DxErrHandler dxeh; //create an instance of an error handler dxeh.HandleDxError(dxresult); //call it to handle the error } } ---------- EXAMPLE 2: ---------- #include "dxerror.h" //include the header and make sure the compiler can //find the dxerror.lib file to link in. void MyFunction() { LPDIRECT3DRM lplpD3DRM; HRESULT dxresult; //HRESULT is DWORD, 32 bits for the result dxresult = Direct3DRMCreate(&lplpD3DRM); if (dxresult != D3DRM_OK) { DxErrHandler dxeh; //create an instance of an error handler //call it to handle the error dxeh.HandleDxError(dxresult, DXERR_FATAL ,"MyFunction Failed"); } } ---------- EXAMPLE 3: ---------- #include "dxerror.h" //include the header and make sure the compiler can //find the dxerror.lib file to link in. void MyErrorFunct() //function to call if error occurs { //code } void MyFunction() { LPDIRECT3DRM lplpD3DRM; HRESULT dxresult; //HRESULT is DWORD, 32 bits for the result dxresult = Direct3DRMCreate(&lplpD3DRM); if (dxresult != D3DRM_OK) { DxErrHandler dxeh; //create an instance of an error handler //call it to handle the error dxeh.HandleDxError(dxresult, MyErrorFunct); } } ---------- EXAMPLE 4: ---------- #include "dxerror.h" //include the header and make sure the compiler can //find the dxerror.lib file to link in. void MyErrFunct() //function to call if error occurs { //code } void MyFunction() { LPDIRECT3DRM lplpD3DRM; HRESULT dxr; //HRESULT is DWORD, 32 bits for the result dxr = Direct3DRMCreate(&lplpD3DRM); if (dxr != D3DRM_OK) { DxErrHandler dxeh; //create an instance of an error handler //call it to handle the error dxeh.HandleDxError(dxr, DXERR_FATAL ,"MyFunction Failed", MyErrFunct); } } -------------------------------------------------------------------------------- Author: Eric Gessner Email: 75700.1057@compuserve.com (any/all feedback will be appreciated). --------------------------------------------------------------------------------